and ffffggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX are part of the GGGGLLLL____SSSSGGGGIIIIXXXX____iiiinnnnssssttttrrrruuuummmmeeeennnnttttssss extension.
Instruments allow an application to measure performance of the GL
pipeline and identify possible bottlenecks. This information may be
useful in feedback-based load management schemes which attempt to
maintain a constant frame-rate, or in tuning an application for best
performance.
GGGGLLLL____SSSSGGGGIIIIXXXX____iiiinnnnssssttttrrrruuuummmmeeeennnnttttssss provides an instrumentation framework, but no
instruments. The set of available instruments varies between OpenGL
implementations, and can be determined by querying the GGGGLLLL____EEEEXXXXTTTTEEEENNNNSSSSIIIIOOOONNNNSSSS
string returned by ffffggggllllGGGGeeeettttSSSSttttrrrriiiinnnngggg for the names of the extensions that
implement the instruments.
Unlike feedback and selection (see ffffggggllllSSSSeeeelllleeeeccccttttBBBBuuuuffffffffeeeerrrr and
ffffggggllllFFFFeeeeeeeeddddbbbbaaaacccckkkkBBBBuuuuffffffffeeeerrrr), GGGGLLLL____SSSSGGGGIIIIXXXX____iiiinnnnssssttttrrrruuuummmmeeeennnnttttssss provides commands that allow
measurements to be delivered asynchronously, so that the graphics
pipeline need not be stalled while measurements are returned to the
client.
A buffer in which to collect instrument measurements is specified with
ffffggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX. _s_i_z_e specifies the size of the buffer, as a
count of GLints. The buffer will be prepared in a way that allows it to
be written asynchronously by the graphics pipeline. If the same _b_u_f_f_e_r
was specified on a previous call, the buffer is reset; that is,
measurements taken after the call to ffffggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX will be
written to the start of the buffer. If _b_u_f_f_e_r is zero, then any
resources allocated by a previous call to prepare the buffer for writing
will be freed. If _b_u_f_f_e_r is non-zero, but is different from a previous
call, the old buffer is replaced by the new buffer and any allocated
resources involved in preparing the old buffer for writing are freed.
The buffer address can be queried with ffffggggllllGGGGeeeettttPPPPooooiiiinnnntttteeeerrrrvvvvEEEEXXXXTTTT using argument
To enable an instrument, use ffffggggllllEEEEnnnnaaaabbbblllleeee with an argument that specifies
the instrument. The argument to use for a particular instrument is
determined by the OpenGL extension that supports that instrument. (See
below for an example.)
To start the currently-enabled instrument(s) call
ffffggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX. To take a measurement use
ffffggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX. To stop the currently-enabled instruments and
take a final measurement use ffffggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX. The parameter
_m_a_r_k_e_r will be passed through the pipe and written to the buffer to ease
the task of interpreting it.
The format of any instrument measurement in the buffer obeys certain
conventions. The first word of the measurement is the ffffggggllllEEEEnnnnaaaabbbblllleeee enum for
the instrument itself. The second word of the measurement is the size in
GLints of the entire measurement so that any parser can step over
measurements with which it is unfamiliar. Currently there are no
implementation independent instruments to describe. Some implementation
dependent instruments are described in the Machine Dependencies section
of this page.
In a single measurement, if multiple instruments are enabled, the data
for those instruments can appear in the buffer in any order.
If no instruments are enabled executing ffffggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX,
ffffggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, or ffffggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssss will not write measurements
to the buffer.
The number of measurements taken since the buffer was reset can be
queried with ffffggggllllGGGGeeeetttt using GGGGLLLL____IIIINNNNSSSSTTTTRRRRUUUUMMMMEEEENNNNTTTT____MMMMEEEEAAAASSSSUUUURRRREEEEMMMMEEEENNNNTTTTSSSS____SSSSGGGGIIIIXXXX.
To determine whether a measurement has been written to the buffer call
ffffggggllllPPPPoooollllllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX. If a new measurement has appeared in the buffer
since the last call to ffffggggllllPPPPoooollllllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, 1 is returned, and the
value of marker associated with the measurement by ffffggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX
or ffffggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX is written into the variable referenced by
_m_a_r_k_e_r__p. The measurements will appear in the buffer in the order in
which they were requested. If the buffer overflows,
ffffggggllllPPPPoooollllllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX may return -1 as soon as the overflow is detected,
even if the measurement being polled did not cause the overflow. (An
implementation may also choose to delay reporting the overflow until the
measurement that caused the overflow is the one being polled.) If no new
measurement has been written to the buffer, and overflow has not
To get a count of the number of new valid GLints written to the buffer,
call ffffggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX. The value returned is the number of GLints
that have been written to the buffer since the last call to
ffffggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX or ffffggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX. If the buffer has
overflowed since the last call to ffffggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, -1 is returned
for the count. Note that ffffggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX can be used independently
of ffffggggllllPPPPoooollllllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX.
and ffffggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX are part of the GGGGLLLL____SSSSGGGGIIIIXXXX____iiiinnnnssssttttrrrruuuummmmeeeennnnttttssss extension,
not part of the core GL command set. See ffffggggllllIIIInnnnttttrrrroooo for information about
using extensions.
EEEERRRRRRRROOOORRRRSSSS
If _s_i_z_e is negative, GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____VVVVAAAALLLLUUUUEEEE is generated.
GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if ffffggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX is executed
twice without an intervening execution of ffffggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX or
ffffggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX. Symmetrically, GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is
generated if ffffggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX is executed twice without an
intervening ffffggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX. ffffggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX will
generate GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN if executed after an execution of
ffffggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssss without an intervening execution of
ffffggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX or ffffggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX. Executing any of
ffffggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, ffffggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, or ffffggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssss
without a successful execution of ffffggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX to define a
buffer will generate GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN.
GGGGLLLL____IIIINNNNVVVVAAAALLLLIIIIDDDD____OOOOPPPPEEEERRRRAAAATTTTIIIIOOOONNNN is generated if any of ffffggggllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssBBBBuuuuffffffffeeeerrrrSSSSGGGGIIIIXXXX,
ffffggggllllPPPPoooollllllllIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX or ffffggggllllGGGGeeeettttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX is executed between the
execution of ffffggggllllBBBBeeeeggggiiiinnnn and the corresponding execution of ffffggggllllEEEEnnnndddd.
ffffggggllllGGGGeeeetttt with argument GGGGLLLL____IIIINNNNSSSSTTTTRRRRUUUUMMMMEEEENNNNTTTT____MMMMEEEEAAAASSSSUUUURRRREEEEMMMMEEEENNNNTTTTSSSS____SSSSGGGGIIIIXXXX
ffffggggllllGGGGeeeettttPPPPooooiiiinnnntttteeeerrrrvvvv with argument GGGGLLLL____IIIINNNNSSSSTTTTRRRRUUUUMMMMEEEENNNNTTTT____BBBBUUUUFFFFFFFFEEEERRRR____PPPPOOOOIIIINNNNTTTTEEEERRRR____SSSSGGGGIIIIXXXX
ffffggggllllGGGGeeeettttSSSSttttrrrriiiinnnngggg with argument GGGGLLLL____EEEEXXXXTTTTEEEENNNNSSSSIIIIOOOONNNNSSSS
COUNTEMPTY (index 2) Increments each clock cycle for which a word of
screen-space geometry, pixel, or texel data was not transferred from
the GE board to the RM board. A high value could indicate that
rendering is geometry-limited or host-limited (because the GE is not
delivering commands to the RM as fast as the RM can process them),
or that rendering is rasterization-limited (because the RM is
working on previous commands and is refusing to accept new data from
the GE). Unfortunately there is no simple way to distinguish
between these two cases. The counter is set to zero by
ffffggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, and by ffffggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX after its
value has been written to the buffer.
COUNTDRAW (index 3) Increments each clock cycle for which a word of
screen-space geometry or pixel data (but not texel data) is
transferred from the GE board to the RM board. The counter is set
to zero by ffffggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, and by ffffggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX
after its value has been written to the buffer.
COUNTLOAD (index 4) Increments each clock cycle for which a word of
texture data is written to the texture memory. The counter is set
to zero by ffffggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX, and by ffffggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX
after its value has been written to the buffer.
MAILBOX_TIMESTAMP (index 5) Contains the value of COUNTALL (see
below) at the time ffffggggllllSSSSttttaaaarrrrttttIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX or ffffggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX
was called.
COUNTALL (index 6) Increments every clock cycle. No effort is made
to prevent wrapping.
PAD (index 7) Unused.
MARKER (index 8) Holds the value of the marker passed to
ffffggggllllSSSSttttooooppppIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX or ffffggggllllRRRReeeeaaaaddddIIIInnnnssssttttrrrruuuummmmeeeennnnttttssssSSSSGGGGIIIIXXXX for this
measurement.
MAILBOX (index 9) Holds a value that is used by the implementation.
Typically a sequence identifier, set after the buffer has been
specified, starting at 1 with the first measurement and incrementing
